GetIconSuite

GetIconSuite
Header:	Icons.h		Carbon status:	Supported

Creates an icon suite in memory that contains handles to a specified icon family’s resources.

OSErr GetIconSuite (
    IconSuiteRef *theIconSuite, 
    SInt16 theResID, 
    IconSelectorValue selector
);

theIconSuite: On return, a pointer to a handle to an icon suite for the requested icon family, for which this function allocates the memory. To release the memory occupied by an icon suite, you must use the DisposeIconSuite function.
theResID: The resource ID of the icons in the icon family to be read into memory. In general, you should specify your icon resources as purgeable.
selector: Indicates which icons from the icon family to include in the icon suite. See “Selector Mask Values” for a description of the values you can use in this parameter.

function result: A result code.

DISCUSSION

When you create an icon suite from icon family resources, the associated resource file should remain open while you use Icon Utilities functions. If you call the SetResLoad function with the load parameter set to FALSE before you call this function, the suite is filled with unloaded resource handles.

When you create an icon suite using this function, it sets the default label for the suite to none. To set a new default label for an icon suite, use the SetSuiteLabel function. To perform operations on one or more icons in an icon suite, use the ForEachIconDo function. To draw the icon described by the icon suite using the icon family member that is most suitable for the current bit depth of the display device, use the PlotIconSuite function.

As an alternative to this function, you can also create an empty icon suite using the NewIconSuite function and then add icons to it one at a time using the AddIconToSuite function.

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.